<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Common SAML issues | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'trb-security-saml.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/trb-security-saml.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/trb-security-saml.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/trb-security-saml.html" rel="nofollow" target="_blank">../en/trb-security-saml.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="security-troubleshooting.html">Troubleshooting security</a></span>
»
<span class="breadcrumb-node">Common SAML issues</span>
</div>
<div class="navheader">
<span class="prev">
<a href="trb-security-kerberos.html">« Common Kerberos exceptions</a>
</span>
<span class="next">
<a href="trb-security-internalserver.html">Internal Server Error in Kibana »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="trb-security-saml"></a>Common SAML issues<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/troubleshooting.asciidoc">edit</a>
</h2>
</div></div></div>
<p>Some of the common SAML problems are shown below with tips on how to resolve
these issues.</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the Elasticsearch
logs:</p>
<pre class="literallayout">Cannot find any matching realm for [SamlPrepareAuthenticationRequest{realmName=saml1,
assertionConsumerServiceURL=https://my.kibana.url/api/security/v1/saml}]</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>In order to initiate a SAML authentication, Kibana needs to know which SAML realm
it should use from the ones that are configured in Elasticsearch. You can use the
<code class="literal">xpack.security.authc.providers.saml.&lt;provider-name&gt;.realm</code> setting to explicitly
set the SAML realm name in Kibana. It must match the name of the SAML realm that is
configured in Elasticsearch.</p>
<p>If you get an error like the one above, it possibly means that the value of
<code class="literal">xpack.security.authc.providers.saml.&lt;provider-name&gt;.realm</code> in your Kibana
configuration is wrong. Verify that it matches the name of the configured realm
in Elasticsearch, which is the string after <code class="literal">xpack.security.authc.realms.saml.</code> in your
Elasticsearch configuration.</p>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the
Elasticsearch logs:</p>
<pre class="literallayout">Authentication to realm saml1 failed - Provided SAML response is not valid for realm
saml/saml1 (Caused by ElasticsearchSecurityException[Conditions [https://some-url-here...]
do not match required audience [https://my.kibana.url]])</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>We received a SAML response that is addressed to another SAML Service Provider.
This usually means that the configured SAML Service Provider Entity ID in
<code class="literal">elasticsearch.yml</code> (<code class="literal">sp.entity_id</code>) does not match what has been configured as
the SAML Service Provider Entity ID in the SAML Identity Provider documentation.</p>
<p>To resolve this issue, ensure that both the saml realm in Elasticsearch and the IdP are
configured with the same string for the SAML Entity ID of the Service Provider.</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>These strings are compared as case-sensitive strings and not as
canonicalized URLs even when the values are URL-like. Be mindful of trailing
slashes, port numbers, etc.</p>
</div>
</div>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the
Elasticsearch logs:</p>
<pre class="literallayout">Cannot find metadata for entity [your:entity.id] in [metadata.xml]</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>We could not find the metadata for the SAML Entity ID <code class="literal">your:entity.id</code> in the
configured metadata file (<code class="literal">metadata.xml</code>).</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Ensure that the <code class="literal">metadata.xml</code> file you are using is indeed the one provided
by your SAML Identity Provider.
</li>
<li class="listitem">
Ensure that the <code class="literal">metadata.xml</code> file contains one &lt;EntityDescriptor&gt; element
as follows: <code class="literal">&lt;EntityDescriptor ID="0597c9aa-e69b-46e7-a1c6-636c7b8a8070" entityID="https://saml.example.com/f174199a-a96e-4201-88f1-0d57a610c522/" ...</code>
where the value of the <code class="literal">entityID</code> attribute is the same as the value of the
<code class="literal">idp.entity_id</code> that you have set in your SAML realm configuration in
<code class="literal">elasticsearch.yml</code>.
</li>
<li class="listitem">
Note that these are also compared as case-sensitive strings and not as
canonicalized URLs even when the values are URL-like.
</li>
</ol>
</div>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the Elasticsearch
logs:</p>
<pre class="literallayout">unable to authenticate user [&lt;unauthenticated-saml-user&gt;]
for action [cluster:admin/xpack/security/saml/authenticate]</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>This error indicates that Elasticsearch failed to process the incoming SAML
authentication message. Since the message can’t be processed, Elasticsearch is not aware
of who the to-be authenticated user is and the <code class="literal">&lt;unauthenticated-saml-user&gt;</code>
placeholder is used instead. To diagnose the <em>actual</em> problem, you must check
the Elasticsearch logs for further details.</p>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the Elasticsearch
logs:</p>
<pre class="literallayout">Authentication to realm &lt;saml-realm-name&gt; failed - SAML Attribute [&lt;AttributeName0&gt;] for
[xpack.security.authc.realms.saml.&lt;saml-realm-name&gt;.attributes.principal] not found in saml attributes
[&lt;AttributeName1&gt;=&lt;AttributeValue1&gt;, &lt;AttributeName2&gt;=&lt;AttributeValue2&gt;, ...] or NameID [ NameID(format)=value ]</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>This error indicates that Elasticsearch failed to find the necessary SAML attribute in the SAML response that the
Identity Provider sent. In this example, Elasticsearch is configured as follows:</p>
<pre class="literallayout">xpack.security.authc.realms.saml.&lt;saml-realm-name&gt;.attributes.principal: AttributeName0</pre>

<p>This configuration means that Elasticsearch expects to find a SAML Attribute with the name <code class="literal">AttributeName0</code> or a <code class="literal">NameID</code> with the appropriate format in the SAML
response so that <a class="xref" href="saml-guide-authentication.html#saml-attribute-mapping" title="Attribute mapping">it can map it</a> to the <code class="literal">principal</code> user property. The <code class="literal">principal</code> user property is a
mandatory one, so if this mapping can’t happen, the authentication fails.</p>
<p>If you are attempting to map a <code class="literal">NameID</code>, make sure that the expected <code class="literal">NameID</code> format matches the one that is sent.
See <a class="xref" href="saml-guide-authentication.html#saml-attribute-mapping-nameid" title="Special attribute names">Special attribute names</a> for more details.</p>
<p>If you are attempting to map a SAML attribute and it is not part of the list in the error message, it might mean
that you have misspelled the attribute name, or that the IdP is not sending this particular attribute. You might
be able to use another attribute from the list to map to <code class="literal">principal</code> or consult with your IdP administrator to
determine if the required attribute can be sent.</p>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the Elasticsearch
logs:</p>
<pre class="literallayout">Cannot find [{urn:oasis:names:tc:SAML:2.0:metadata}IDPSSODescriptor]/[urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect] in descriptor</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>This error indicates that the SAML metadata for your Identity Provider do not contain a <code class="literal">&lt;SingleSignOnService&gt;</code> endpoint with binding of
HTTP-Redirect (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect). Elasticsearch supports only the <code class="literal">HTTP-Redirect</code> binding for SAML authentication
requests (and it doesn’t support the <code class="literal">HTTP-POST</code> binding). Consult your IdP administrator in order to enable at least one
<code class="literal">&lt;SingleSignOnService&gt;</code> supporting <code class="literal">HTTP-Redirect</code> binding and update your IdP SAML Metadata.</p>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the
Elasticsearch logs:</p>
<pre class="literallayout">Authentication to realm my-saml-realm failed -
Provided SAML response is not valid for realm saml/my-saml-realm
(Caused by ElasticsearchSecurityException[SAML Response is not a 'success' response:
 The SAML IdP did not grant the request. It indicated that the Elastic Stack side sent
 something invalid (urn:oasis:names:tc:SAML:2.0:status:Requester). Specific status code which might
 indicate what the issue is: [urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy]]
)</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>This means that the SAML Identity Provider failed to authenticate the user and
sent a SAML Response to the Service Provider (Elastic Stack) indicating this failure.
The message will convey whether the SAML Identity Provider thinks that the problem
is with the Service Provider (Elastic Stack) or with the Identity Provider itself and
the specific status code that follows is extremely useful as it usually indicates
the underlying issue. The list of specific error codes is defined in the
<a href="https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf" class="ulink" target="_top">SAML 2.0 Core specification - Section 3.2.2.2</a>
and the most commonly encountered ones are:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<code class="literal">urn:oasis:names:tc:SAML:2.0:status:AuthnFailed</code>: The SAML Identity Provider failed to
authenticate the user. There is not much to troubleshoot on the Elastic Stack side for this status, the logs of
the SAML Identity Provider will hopefully offer much more information.
</li>
<li class="listitem">
<code class="literal">urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy</code>: The SAML Identity Provider cannot support
releasing a NameID with the requested format. When creating SAML Authentication Requests, Elasticsearch sets
the NameIDPolicy element of the Authentication request with the appropriate value. This is controlled
by the <a href="security-settings.html#ref-saml-settings" class="ulink" target="_top"><code class="literal">nameid_format</code></a> configuration parameter in
<code class="literal">elasticsearch.yml</code>, which if not set defaults to <code class="literal">urn:oasis:names:tc:SAML:2.0:nameid-format:transient</code>.
 This instructs the Identity Provider to return a NameID with that specific format in the SAML Response. If
the SAML Identity Provider cannot grant that request, for example because it is configured to release a
NameID format with <code class="literal">urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</code> format instead, it returns this error
indicating an invalid NameID policy. This issue can be resolved by adjusting <code class="literal">nameid_format</code> to match the format
the SAML Identity Provider can return or by setting it to <code class="literal">urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</code>
so that the Identity Provider is allowed to return any format it wants.
</li>
</ol>
</div>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Authentication in Kibana fails and the following error is printed in the
Elasticsearch logs:</p>
<pre class="literallayout">The XML Signature of this SAML message cannot be validated. Please verify that the saml
realm uses the correct SAMLmetadata file/URL for this Identity Provider</pre>

<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>This means that Elasticsearch failed to validate the digital signature of the SAML
message that the Identity Provider sent. Elasticsearch uses the public key of the
Identity Provider that is included in the SAML metadata, in order to validate
the signature that the IdP has created using its corresponding private key.
Failure to do so, can have a number of causes:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
As the error message indicates, the most common cause is that the wrong
metadata file is used and as such the public key it contains doesn’t correspond
to the private key the Identity Provider uses.
</li>
<li class="listitem">
The configuration of the Identity Provider has changed or the key has been
rotated and the metadata file that Elasticsearch is using has not been updated.
</li>
<li class="listitem">
The SAML Response has been altered in transit and the signature cannot be
validated even though the correct key is used.
</li>
</ol>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The private keys and public keys and self-signed X.509 certificates that
are used in SAML for digital signatures as described above have no relation to
the keys and certificates that are used for TLS either on the transport or the
http layer. A failure such as the one described above has nothing to do with
your <code class="literal">xpack.ssl</code> related configuration.</p>
</div>
</div>
</li>
<li class="listitem">
<p><span class="strong strong"><strong>Symptoms:</strong></span></p>
<p>Users are unable to login with a local username and password in Kibana because
SAML is enabled.</p>
<p><span class="strong strong"><strong>Resolution:</strong></span></p>
<p>If you want your users to be able to use local credentials to authenticate to
Kibana in addition to using the SAML realm for Single Sign-On, you must enable
the <code class="literal">basic</code> <code class="literal">authProvider</code> in Kibana. The process is documented in the
<a class="xref" href="saml-kibana.html#saml-kibana-basic" title="Supporting SAML and basic authentication in Kibana">SAML Guide</a></p>
</li>
</ol>
</div>
<p><span class="strong strong"><strong>Logging:</strong></span></p>
<p>Very detailed trace logging can be enabled specifically for the SAML realm by
setting the following transient setting:</p>
<div class="pre_wrapper lang-shell">
<pre class="programlisting prettyprint lang-shell">PUT /_cluster/settings
{
  "transient": {
    "logger.org.elasticsearch.xpack.security.authc.saml": "trace"
  }
}</pre>
</div>
<p>Alternatively, you can add the following lines to the end of the
<code class="literal">log4j2.properties</code> configuration file in the <code class="literal">ES_PATH_CONF</code>:</p>
<div class="pre_wrapper lang-properties">
<pre class="programlisting prettyprint lang-properties">logger.saml.name = org.elasticsearch.xpack.security.authc.saml
logger.saml.level = TRACE</pre>
</div>
</div>
<div class="navfooter">
<span class="prev">
<a href="trb-security-kerberos.html">« Common Kerberos exceptions</a>
</span>
<span class="next">
<a href="trb-security-internalserver.html">Internal Server Error in Kibana »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>